<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="" content="">
<title>scmgr</title>
  <style type="text/css">
   TABLE {
       background: #aaa;
       color: black; 
   }
   TD {
       background: #eee;
       padding: 5px;
       border: 1px solid #000;
       font-size: 13pt;
   }
   /*h1 {
       font-family: Arial;
       font-size: 28pt;
       font-weight: bold;
   }
   h3 {
       font-size: 30pt;
       font-weight: bold;
   }*/ 
   p {
     font-size: 14pt;
   }   
   .li1 {
     font: 13pt sans-serif;
     font-style: normal;
   }   
   .li2 {
     font: 11pt sans-serif;
     font-style: italic;
   }   
  </style>    
</head>
<body>
<h1>KiCad Schematic Component Manager User's Manual</h1>

<h2>General</h2>

<p>Schematic Component Manager (SCM) is intended for simplifying property editing.</p>

<h3>Features:</h3>

  <ul>
   <font  class="li1">
   <li>Table representation of component list.</li>
   <li>Automating of component selection.</li>
     <ul>
      <font  class="li2">
       <li>Dedicated Selector tool.</li>
       <li>Using component property as selection criteria.</li>
       <li>Flexible rules for property matching: same, different, regular expression.</li>
       <li>Use any component as template for property list.</li>
      </font>
     </ul>
   <li>Group editing of selected componets.</li>
     <ul>
      <font  class="li2">
       <li>Convenient Inspector tool.</li>
       <li>Add/Delete/Rename of component[s] properties.</li>
       <li>Property value substitutions.</li>
       <li>Property templates: generating property value using template.</li>
      </font>
     </ul>
   <li>Customization of components table view.</li>
   <li>Delicate schematic files handling - preserve file sturcture over open/save operations.</li>
   <li>Multisheet schematic support.</li>
   <li>Automatic save/restore all GUI geometry properties.</li>
   </font>
  </ul>

  
<h3>Description:</h3>  

<p>Schematic Component Manager contains three tools:</p>  

<ul>
  <font class="li1">
    <li>Components Table. Represents all schematic components in two-columns table view: <b>Ref | Description</b>.</li>
    <li>Selector. Offers capabilities to select components. Selected components are highlighted in 
        Components Table tool, automatically loaded in Inspector Tool (see below) and selected components count 
        displayed in status line.</li>
    <li>Inspector. Allows group property editing of selected components. Inspector consists of two subtools: Property Inspector
        and Field Inspector.</li>
  </font>
</ul>
  
<h2>Components Table</h2>

<p>Components Table intended for displaying main componets data in breif list view, manually 
selecting of components and review of results of Selector Tool use.</p>

<h3>Components Table controls</h3>
<p></p>
<table>
    <tr>
      <td><b>Name</b></td>
      <td><b>Controls</b></td>
    </tr>
    <tr>
      <td>Navigation</td>
      <td>Up/Down keys</td>
    </tr>
    <tr>
      <td>Load current component</td>
      <td>Enter key or mouse click</td>
    </tr>
    <tr>
      <td>Load multiple components</td>
      <td>Ctrl+click: add single component; Shift+click: add several components</td>
    </tr>
</table>

<p>Components Table description column view can be customized by specifying template pattern for each
component reference prefix - see <a href="settings.html">Settings Dialog</a></p>

<h2>Selector</h2>

<p>Selector tool allows to select components using property parameters as criteria. This greatly simplify 
preparing list of components for editing. Property name, value and other parameters can be typed manually or
easely selected from drop-down list that contains only context-related values.</p>

<p>Selector tool implemented as hierarchical three-columns table: 

<ol>
  <font  class="li1">
    <li>the first column contains property/parameter name;</li>
    <li>the second column contains property/parameter value;</li>
    <li>the third column offer selection option. Selection option can have five values:</li>
        <ol>
          <font  class="li2">
            <li><b>Empty</b>. Property/parameter ignored.</li>
            <li><b>=</b>. Exactly match property/parameter value.</li>
            <li><b>!=</b>. Non-match property/parameter value.</li>
            <li><b>=re</b>. Match regular expression property/parameter value.</li>
            <li><b>!=re</b>. Non-match regular expression property/parameter value.</li>
          </font>
        </ol>
  </font>
</ol>

<p>Properties with internal parameters (field properties) have light-gray background. These 
properties can be expanded (and collapsed) to access internal data by mouse click at the point left from
property name. Also, keyboard can be used to expand/collapse such properties (see Selector controls table below).</p>

<h3>Selector controls</h3>
<p></p>
<table>
    <tr>
      <td><b>Name</b></td>
      <td><b>Controls</b></td>
    </tr>
    <tr>
      <td>Navigation</td>
      <td>Up/Down/Left/Right keys</td>
    </tr>
    <tr>
      <td>Expand/Collapse property</td>
      <td>Ctrl+Down/Ctrl+Up keys</td>
    </tr>
    <tr>
      <td>Edit/save property</td>
      <td>Enter key</td>
    </tr>
    <tr>
      <td>Discard property changes</td>
      <td>Escape key</td>
    </tr>
    <tr>
      <td>Drop down item list</td>
      <td>Alt+Up/Alt+Down keys</td>
    </tr>
</table>

<p>The user can add properties as selection criteria. Another way is to use
any component as template. Selector tool has three buttons to carry out 
typical actions:</p>

<ul>
  <font class="li1">
    <li><b>Use Component</b>. Use current component (that is selected) in Components 
        Table tool as template - all component proerties are copied in Selector
         Tool table.</li>
    <li><b>Apply</b>. Process schematic components to select group of components that
           match selection criterias. Count of selected components displayed in status 
           line.</li>
    <li><b>Clear</b>. Removes all items from Selector tool table.</li>
  </font>
</ul>

<h2>Inspector</h2>

<p>Inspector tool is intended for group editing of properties of selected components.
Inspector tool consists of two sub-tools:</p>
<ul>
  <font class="li1">
    <li>Property Inspector tool.</li>
    <li>Field Inspector tool.</li>
  </font>
</ul>

<p>Property Inspector allows view and edit components properties values. Field Inspector operates
 on the same manner but work with internal property parameters (field data).</p>

<p>Each component has standard property set that is always available in Inspector. Any 
user-defined property presents in Inspector only when this property exists in each selected
component. Property value cell editor is context-based: in case of single value the editor
is simple text-string editor; in case of multiple values the editor is editable combo box.</p>

<h3>Inspector controls</h3>
<p></p>
<table>
    <tr>
      <td><b>Name</b></td>
      <td><b>Controls</b></td>
    </tr>
    <tr>
      <td>Navigation</td>
      <td>Up/Down arrow keys</td>
    </tr>
    <tr>
      <td>Edit/save property</td>
      <td>Enter key</td>
    </tr>
    <tr>
      <td>Discard property changes</td>
      <td>Escape key</td>
    </tr>
    <tr>
      <td>Drop down item list</td>
      <td>Alt+Up/Alt+Down keys</td>
    </tr>
</table>

<p>Property Inspector subtool support text substituting in property values.
If value string contains reference to another property (substitution pattern)
 the reference will replaced with the corresponding value. The reference 
 consists of leading "$" symbol and the referenced property name - for 
 example, <i>"$Type"</i> is reference to property <i>"Type"</i>. Also, one
 more form of the references supported: <i>"${property-name}"</i>. This form is
 suitable when property name has white spaces or when the reference concatinating
 with other part of string without white spaces. For example:</p>
 
 <p><i>"${Vendor ID}"</i>, <i>"${Capacitor Type} ${Nominal}$Units"</i> </p>

<p>Another feature to automate property value generation is property templates.
Property template is user-defined dedicated property with name consisting of
"@" symbol and target property name. For example, <i>"@Value"</i> is property 
template that targeted to <i>"Value"</i> property. Value of the property  
template can contain plain text and substitution patterns (references to the
other component properties). The value of the property template is not changed
but used to construct result string that is used as value of the target 
component property. This allows to create complex property values using
other component properties as sources. For example, some component has the
following properties:</p>

<p></p>
<table>
    <tr>
         <td><b>Property Name</b></td>
         <td><b>Property Value</b></td>
    </tr>
    <tr>
         <td>Value</td>
         <td>ceramic capacitor</td>
    </tr>
    <tr>
         <td>Type</td>
         <td>X7R</td>
    </tr>
    <tr>
         <td>Footprint</td>
         <td>CAP0603</td>
    </tr>
    <tr>
         <td>Nominal</td>
         <td>0.1uF</td>
    </tr>
    <tr>
         <td>Tolerance</td>
         <td>5%</td>
    </tr>
    <tr>
         <td>Voltage</td>
         <td>50V</td>
    </tr>
    <tr>
         <td>@Value</td>
         <td>Capacitor $Nominal $Tolerance $Voltage $Type $Footprint</td>
    </tr>
</table>

<p>The resulting value of the component property <i>"Value"</i>: will be:</p>

<p><i>Capacitor 0.1uF %5 50V X7R CAP0603</i></p>


<h2>Settings</h2>

<p>There are some features that require customization.</p>

<p> First, Components Table <b>Description</b> column view can be tuned 
by user to improve convenience and usability.</p>

<p>Next, some schematics contain components that are not true components - such
as power symbols, custom bus entry points and so on. There is no need to work
with these components, therefore the components should not be loaded to Components Table
tool. This can be done by adding corresponding component prefixes to ignore list.</p>

<p>See <a href="settings.html">Settings Dialog</a> for details</p>
</body>
</html>

